/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
/* vim:set et sts=4: */
/* IBust - IBus with Traditional interface
 * Copyright(c) 2013 Daniel Sun
 * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
 * Copyright (C) 2008-2010 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#if !defined (__IBUST_H_INSIDE__) && !defined (IBUST_COMPILATION)
#error "Only <ibust.h> can be included directly"
#endif

#ifndef __IBUST_PROPERTY_H_
#define __IBUST_PROPERTY_H_

#include "ibustserializable.h"
#include "ibusttext.h"

/**
 * SECTION: ibustproperty
 * @short_description: UI component for input method engine property.
 * @title: IBustProperty
 * @stability: Stable
 *
 * An IBustProperty is an UI component like a button or a menu item
 * which shows the status of corresponding input method engine property.
 * End user can operate and see the current status of IME through these components.
 * For example, ibust-chewing users change the English/Chinese input mode by
 * pressing ctrl-space or click on the Eng/Chi switch button.
 * And the IBustProperty shows the change correspondingly.
 *
 * see_also: #IBustPropList, #IBustEngine
 */
G_BEGIN_DECLS

/*
 * Type macros.
 */
/* define IBustProperty macros */
#define IBUST_TYPE_PROPERTY             \
    (ibust_property_get_type ())
#define IBUST_PROPERTY(obj)             \
    (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUST_TYPE_PROPERTY, IBustProperty))
#define IBUST_PROPERTY_CLASS(klass)     \
    (G_TYPE_CHECK_CLASS_CAST ((klass), IBUST_TYPE_PROPERTY, IBustPropertyClass))
#define IBUST_IS_PROPERTY(obj)          \
    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUST_TYPE_PROPERTY))
#define IBUST_IS_PROPERTY_CLASS(klass)  \
    (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUST_TYPE_PROPERTY))
#define IBUST_PROPERTY_GET_CLASS(obj)   \
    (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUST_TYPE_PROPERTY, IBustPropertyClass))

/**
 * IBustPropType:
 * @PROP_TYPE_NORMAL: Property is shown as normal text.
 * @PROP_TYPE_TOGGLE: Property is shown as a toggle button.
 * @PROP_TYPE_RADIO: Property is shown as a radio selection option.
 * @PROP_TYPE_MENU: Property is shown as a menu, usually imply it has sub menu
 * items.
 * @PROP_TYPE_SEPARATOR: A separator for menu.
 *
 * Type enumeration of IBustProperty.
 */
typedef enum {
    PROP_TYPE_NORMAL = 0,
    PROP_TYPE_TOGGLE = 1,
    PROP_TYPE_RADIO = 2,
    PROP_TYPE_MENU = 3,
    PROP_TYPE_SEPARATOR = 4,
} IBustPropType;

/**
 * IBustPropState:
 * @PROP_STATE_UNCHECKED: Property option is unchecked.
 * @PROP_STATE_CHECKED: Property option is checked.
 * @PROP_STATE_INCONSISTENT: The state is inconsistent with the associated IME
 * property.
 *
 * State of #IBustProperty. The actual effect depends on #IBustPropType of the
 * IBustProperty.
 *
 * <variablelist>
 *     <varlistentry>
 *         <term>PROP_TYPE_TOGGLE</term>
 *         <listitem><para>Emphasized if PROP_STATE_CHECKED, normal otherwise.</para></listitem>
 *     </varlistentry>
 *     <varlistentry>
 *         <term>PROP_TYPE_RADIO</term>
 *         <listitem><para>Option checked if PROP_STATE_CHECKED, unchecked otherwise.</para></listitem>
 *     </varlistentry>
 * </variablelist>
 * No effect on other types.
 */
typedef enum {
    PROP_STATE_UNCHECKED = 0,
    PROP_STATE_CHECKED = 1,
    PROP_STATE_INCONSISTENT = 2,
} IBustPropState;


typedef struct _IBustProperty IBustProperty;
typedef struct _IBustPropertyClass IBustPropertyClass;
typedef struct _IBustPropertyPrivate IBustPropertyPrivate;

#ifndef __PROPLIST_DEFINED
#define __PROPLIST_DEFINED
typedef struct _IBustPropList IBustPropList;
typedef struct _IBustPropListClass IBustPropListClass;
#endif

/**
 * IBustProperty:
 * key: Unique Identity for the IBustProperty.
 * icon: Icon file for the IBustProperty.
 * label: Text shown in UI.
 * symbol: A symbol char showned on a button or status icon for IBustProperty.
 * tooltip: Message shown if mouse hovered the  IBustProperty.
 * sensitive: Whether the IBustProperty is sensitive to keyboard and mouse event.
 * visible: Whether the IBustProperty is visible.
 * type: IBustPropType of IBustProperty.
 * state: IBustPropState of IBustProperty.
 * sub_props: IBustPropList that contains sub IBustProperties. These IBustProperties are usually
 * shown as sub menu item.
 *
 * UI component for input method engine property.
 */
struct _IBustProperty {
    /*< private >*/
    IBustSerializable parent;
    IBustPropertyPrivate *priv;

    gpointer pdummy[7];
};

struct _IBustPropertyClass {
    IBustSerializableClass parent;
};

GType            ibust_property_get_type     ();

/**
 * ibust_property_new:
 * @key: Unique Identity for the #IBustProperty.
 * @type: #IBustPropType of #IBustProperty.
 * @label: Text shown in UI.
 * @icon: (allow-none): Icon file for the #IBustProperty.
 * @tooltip: Message shown if mouse hovered the  #IBustProperty.
 * @sensitive: Whether the #IBustProperty is sensitive to keyboard and mouse event.
 * @visible: Whether the #IBustProperty is visible.
 * @state: IBustPropState of #IBustProperty.
 * @prop_list: (allow-none): #IBustPropList that contains sub IBustProperties.
 * @returns: A newly allocated #IBustProperty.
 *
 * New a #IBustProperty.
 */
IBustProperty    *ibust_property_new          (const gchar    *key,
                                             IBustPropType    type,
                                             IBustText       *label,
                                             const gchar    *icon,
                                             IBustText       *tooltip,
                                             gboolean        sensitive,
                                             gboolean        visible,
                                             IBustPropState   state,
                                             IBustPropList   *prop_list);

/**
 * ibust_property_new_varargs:
 * @first_property_name: Name of the first property.
 * @Varargs: the NULL-terminated arguments of the properties and values.
 *
 * New a #IBustProperty.
 * ibust_property_new_varargs() supports the va_list format.
 * name property is required. e.g.
 * ibust_property_new_varargs("key", "TypingMode", "type", PROP_TYPE_MENU, NULL)
 */
IBustProperty    *ibust_property_new_varargs  (const gchar    *first_property_name,
                                                             ...);

/**
 * ibust_property_get_key:
 * @prop: An #IBustProperty.
 * @returns: the key of #IBustProperty. Should not be freed.
 *
 * Get the key of #IBustProperty.
 */
const gchar *    ibust_property_get_key      (IBustProperty   *prop);

/**
 * ibust_property_get_label:
 * @prop: An #IBustProperty.
 * @returns: (transfer none): the label of #IBustProperty. Should not be freed.
 *
 * Get the label of #IBustProperty.
 */
IBustText *       ibust_property_get_label    (IBustProperty   *prop);

/**
 * ibust_property_set_label:
 * @prop: An #IBustProperty.
 * @label: Text shown in UI.
 *
 * Set the label of #IBustProperty.
 */
void             ibust_property_set_label    (IBustProperty   *prop,
                                             IBustText       *label);

/**
 * ibust_property_get_symbol:
 * @prop: An #IBustProperty.
 * @returns: (transfer none): the symbol of #IBustProperty. Should not be freed.
 *
 * Get the symbol of #IBustProperty.
 */
IBustText *       ibust_property_get_symbol   (IBustProperty   *prop);

/**
 * ibust_property_set_symbol:
 * @prop: An #IBustProperty.
 * @symbol: Text shown in UI.
 *
 * Set the symbol of #IBustProperty.
 */
void             ibust_property_set_symbol   (IBustProperty   *prop,
                                             IBustText       *symbol);

/**
 * ibust_property_get_icon:
 * @prop: An #IBustProperty.
 * @returns: the icon of #IBustProperty. Should not be freed.
 *
 * Get the icon of #IBustProperty.
 */
const gchar *    ibust_property_get_icon     (IBustProperty   *prop);

/**
 * ibust_property_set_icon:
 * @prop: An #IBustProperty.
 * @icon: Icon shown in UI. It could be a full path of an icon file or an icon name.
 *
 * Set the icon of #IBustProperty.
 */
void             ibust_property_set_icon     (IBustProperty   *prop,
                                             const gchar    *icon);

/**
 * ibust_property_get_tooltip:
 * @prop: An #IBustProperty.
 * @returns: (transfer none): the tooltip of #IBustProperty. Should not be freed.
 *
 * Get the tooltip of #IBustProperty.
 */
IBustText *       ibust_property_get_tooltip  (IBustProperty   *prop);

/**
 * ibust_property_set_tooltip:
 * @prop: An #IBustProperty.
 * @tooltip: Text of the tooltip.
 *
 * Set the tooltip of #IBustProperty.
 */
void             ibust_property_set_tooltip  (IBustProperty   *prop,
                                             IBustText       *tooltip);

/**
 * ibust_property_get_sensitive:
 * @prop: An #IBustProperty.
 * @returns: the sensitive of #IBustProperty.
 *
 * Get the sensitive of #IBustProperty.
 */
gboolean         ibust_property_get_sensitive(IBustProperty   *prop);

/**
 * ibust_property_set_sensitive:
 * @prop: An #IBustProperty.
 * @sensitive: Whether the #IBustProperty is sensitive.
 *
 * Set whether the #IBustProperty is sensitive.
 */
void             ibust_property_set_sensitive(IBustProperty   *prop,
                                             gboolean        sensitive);

/**
 * ibust_property_get_visible:
 * @prop: An #IBustProperty.
 * @returns: the visible of #IBustProperty.
 *
 * Get the visible of #IBustProperty.
 */
gboolean         ibust_property_get_visible  (IBustProperty   *prop);

/**
 * ibust_property_set_visible:
 * @prop: An #IBustProperty.
 * @visible: Whether the #IBustProperty is visible.
 *
 * Set whether the #IBustProperty is visible.
 */
void             ibust_property_set_visible  (IBustProperty   *prop,
                                             gboolean        visible);

/**
 * ibust_property_get_property_type:
 * @prop: An #IBustProperty.
 * @returns: the type of #IBustProperty.
 *
 * Get the type of #IBustProperty.
 */
IBustPropType     ibust_property_get_prop_type(IBustProperty   *prop);

/**
 * ibust_property_get_state:
 * @prop: An #IBustProperty.
 * @returns: the state of #IBustProperty.
 *
 * Get the state of #IBustProperty.
 */
IBustPropState    ibust_property_get_state    (IBustProperty   *prop);

/**
 * ibust_property_set_state:
 * @prop: An #IBustProperty.
 * @state: The state of the #IBustProperty.
 *
 * Set the state of the #IBustProperty.
 */
void             ibust_property_set_state    (IBustProperty   *prop,
                                             IBustPropState   state);

/**
 * ibust_property_get_sub_props:
 * @prop: An #IBustProperty.
 * @returns: (transfer none): the IBustPropList of #IBustProperty.
 *     Should not be freed.
 *
 * Get the IBustPropList of #IBustProperty.
 */
IBustPropList *   ibust_property_get_sub_props(IBustProperty   *prop);

/**
 * ibust_property_set_sub_props:
 * @prop: An #IBustProperty.
 * @prop_list: #IBustPropList that contains sub IBustProperties.
 *
 * Set the sub IBustProperties.
 */
void             ibust_property_set_sub_props(IBustProperty   *prop,
                                             IBustPropList   *prop_list);

/**
 * ibust_property_update:
 * @prop: An #IBustProperty.
 * @prop_update: #IBustPropList that contains sub IBustProperties.
 * @returns: TRUE for update suceeded; FALSE otherwise.
 *
 * Update the content of an #IBustProperty.
 * #IBustProperty @prop_update can either be sub-property of @prop,
 * or holds new values for @prop.
 */

gboolean         ibust_property_update       (IBustProperty   *prop,
                                             IBustProperty   *prop_update);

G_END_DECLS
#endif
